@types/unist

What is @types/unist?

The @types/unist package provides TypeScript definitions for Unist, a specification for syntax trees. It is used to add static typing to Unist-based projects, enabling developers to work with Unist syntax trees in a type-safe manner. This package is essential for TypeScript developers working with Unist or any Unist-compatible syntax tree, such as Markdown Abstract Syntax Trees (ASTs), providing auto-completion and type checking.

What are @types/unist's main functionalities?

Node Type Definition

Defines the basic structure of a Unist node, including types like 'text', 'element', etc. This is fundamental for creating and manipulating syntax trees.

{
  "type": "text",
  "value": "Hello, world!"
}

Parent Type Definition

Defines a parent node which can contain other nodes. This is crucial for representing hierarchical structures within syntax trees.

{
  "type": "paragraph",
  "children": [
    {
      "type": "text",
      "value": "Hello, world!"
    }
  ]
}

Literal Type Definition

Defines a literal node with a value. This is used for nodes that contain actual content, such as text.

{
  "type": "text",
  "value": "Example text"
}

Other packages similar to @types/unist

@types/mdast

Provides TypeScript definitions for MDAST, a Markdown Abstract Syntax Tree format. It is similar to @types/unist in that it offers type definitions for a specific syntax tree format, but it is specifically tailored to Markdown, whereas @types/unist is more general.

@types/hast

Offers TypeScript definitions for HAST, an HTML Abstract Syntax Tree format. Like @types/unist, it provides type definitions for working with syntax trees, but focuses on HTML content.

remark

A Markdown processor powered by plugins part of the unified ecosystem. While not a type package itself, it uses Unist under the hood for its syntax tree. It demonstrates a practical application of Unist, showing how @types/unist can be applied in real-world projects.

README

Installation

npm install --save @types/unist

Summary

This package contains type definitions for unist (https://github.com/syntax-tree/unist).

Details

Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/unist/v2.

index.d.ts

/**
 * Syntactic units in unist syntax trees are called nodes.
 *
 * @typeParam TData Information from the ecosystem. Useful for more specific {@link Node.data}.
 */
export interface Node<TData extends object = Data> {
    /**
     * The variant of a node.
     */
    type: string;

    /**
     * Information from the ecosystem.
     */
    data?: TData | undefined;

    /**
     * Location of a node in a source document.
     * Must not be present if a node is generated.
     */
    position?: Position | undefined;
}

/**
 * Information associated by the ecosystem with the node.
 * Space is guaranteed to never be specified by unist or specifications
 * implementing unist.
 */
export interface Data {
    [key: string]: unknown;
}

/**
 * Location of a node in a source file.
 */
export interface Position {
    /**
     * Place of the first character of the parsed source region.
     */
    start: Point;

    /**
     * Place of the first character after the parsed source region.
     */
    end: Point;

    /**
     * Start column at each index (plus start line) in the source region,
     * for elements that span multiple lines.
     */
    indent?: number[] | undefined;
}

/**
 * One place in a source file.
 */
export interface Point {
    /**
     * Line in a source file (1-indexed integer).
     */
    line: number;

    /**
     * Column in a source file (1-indexed integer).
     */
    column: number;
    /**
     * Character in a source file (0-indexed integer).
     */
    offset?: number | undefined;
}

/**
 * Util for extracting type of {@link Node.data}
 *
 * @typeParam TNode Specific node type such as {@link Node} with {@link Data}, {@link Literal}, etc.
 *
 * @example `NodeData<Node<{ key: string }>>` -> `{ key: string }`
 */
export type NodeData<TNode extends Node<object>> = TNode extends Node<infer TData> ? TData : never;

/**
 * Nodes containing other nodes.
 *
 * @typeParam ChildNode Node item of {@link Parent.children}
 */
export interface Parent<ChildNode extends Node<object> = Node, TData extends object = NodeData<ChildNode>>
    extends Node<TData>
{
    /**
     * List representing the children of a node.
     */
    children: ChildNode[];
}

/**
 * Nodes containing a value.
 *
 * @typeParam Value Specific value type of {@link Literal.value} such as `string` for `Text` node
 */
export interface Literal<Value = unknown, TData extends object = Data> extends Node<TData> {
    value: Value;
}

Additional Details

• Last updated: Thu, 15 Aug 2024 02:18:53 GMT
• Dependencies: none

Credits

These definitions were written by bizen241, Jun Lu, Hernan Rajchert, Titus Wormer, Junyoung Choi, Ben Moon, and JounQin.